home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 1998 November
/
Freeware November 1998.img
/
dist
/
fw_elisp-manual-19.idb
/
usr
/
freeware
/
info
/
elisp-5.z
/
elisp-5
(
.txt
)
Wrap
GNU Info File
|
1998-05-26
|
45KB
|
927 lines
This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual. It corresponds to Emacs Version 19.34.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp, Node: Formatting Strings, Next: Character Case, Prev: String Conversion, Up: Strings and Characters
Formatting Strings
==================
"Formatting" means constructing a string by substitution of computed
values at various places in a constant string. This string controls
how the other values are printed as well as where they appear; it is
called a "format string".
Formatting is often useful for computing messages to be displayed.
In fact, the functions `message' and `error' provide the same
formatting feature described here; they differ from `format' only in
how they use the result of formatting.
- Function: format STRING &rest OBJECTS
This function returns a new string that is made by copying STRING
and then replacing any format specification in the copy with
encodings of the corresponding OBJECTS. The arguments OBJECTS are
the computed values to be formatted.
A format specification is a sequence of characters beginning with a
`%'. Thus, if there is a `%d' in STRING, the `format' function
replaces it with the printed representation of one of the values to be
formatted (one of the arguments OBJECTS). For example:
(format "The value of fill-column is %d." fill-column)
=> "The value of fill-column is 72."
If STRING contains more than one format specification, the format
specifications correspond with successive values from OBJECTS. Thus,
the first format specification in STRING uses the first such value, the
second format specification uses the second such value, and so on. Any
extra format specifications (those for which there are no corresponding
values) cause unpredictable behavior. Any extra values to be formatted
are ignored.
Certain format specifications require values of particular types.
However, no error is signaled if the value actually supplied fails to
have the expected type. Instead, the output is likely to be
meaningless.
Here is a table of valid format specifications:
Replace the specification with the printed representation of the
object, made without quoting. Thus, strings are represented by
their contents alone, with no `"' characters, and symbols appear
without `\' characters.
If there is no corresponding object, the empty string is used.
Replace the specification with the printed representation of the
object, made with quoting. Thus, strings are enclosed in `"'
characters, and `\' characters appear where necessary before
special characters.
If there is no corresponding object, the empty string is used.
Replace the specification with the base-eight representation of an
integer.
Replace the specification with the base-ten representation of an
integer.
Replace the specification with the base-sixteen representation of
an integer.
Replace the specification with the character which is the value
given.
Replace the specification with the exponential notation for a
floating point number.
Replace the specification with the decimal-point notation for a
floating point number.
Replace the specification with notation for a floating point
number, using either exponential notation or decimal-point
notation whichever is shorter.
A single `%' is placed in the string. This format specification is
unusual in that it does not use a value. For example, `(format "%%
%d" 30)' returns `"% 30"'.
Any other format character results in an `Invalid format operation'
error.
Here are several examples:
(format "The name of this buffer is %s." (buffer-name))
=> "The name of this buffer is strings.texi."
(format "The buffer object prints as %s." (current-buffer))
=> "The buffer object prints as strings.texi."
(format "The octal value of %d is %o,
and the hex value is %x." 18 18 18)
=> "The octal value of 18 is 22,
and the hex value is 12."
All the specification characters allow an optional numeric prefix
between the `%' and the character. The optional numeric prefix defines
the minimum width for the object. If the printed representation of the
object contains fewer characters than this, then it is padded. The
padding is on the left if the prefix is positive (or starts with zero)
and on the right if the prefix is negative. The padding character is
normally a space, but if the numeric prefix starts with a zero, zeros
are used for padding.
(format "%06d is padded on the left with zeros" 123)
=> "000123 is padded on the left with zeros"
(format "%-6d is padded on the right" 123)
=> "123 is padded on the right"
`format' never truncates an object's printed representation, no
matter what width you specify. Thus, you can use a numeric prefix to
specify a minimum spacing between columns with no risk of losing
information.
In the following three examples, `%7s' specifies a minimum width of
7. In the first case, the string inserted in place of `%7s' has only 3
letters, so 4 blank spaces are inserted for padding. In the second
case, the string `"specification"' is 13 letters wide but is not
truncated. In the third case, the padding is on the right.
(format "The word `%7s' actually has %d letters in it."
"foo" (length "foo"))
=> "The word ` foo' actually has 3 letters in it."
(format "The word `%7s' actually has %d letters in it."
"specification" (length "specification"))
=> "The word `specification' actually has 13 letters in it."
(format "The word `%-7s' actually has %d letters in it."
"foo" (length "foo"))
=> "The word `foo ' actually has 3 letters in it."
File: elisp, Node: Character Case, Next: Case Table, Prev: Formatting Strings, Up: Strings and Characters
Character Case
==============
The character case functions change the case of single characters or
of the contents of strings. The functions convert only alphabetic
characters (the letters `A' through `Z' and `a' through `z'); other
characters are not altered. The functions do not modify the strings
that are passed to them as arguments.
The examples below use the characters `X' and `x' which have ASCII
codes 88 and 120 respectively.
- Function: downcase STRING-OR-CHAR
This function converts a character or a string to lower case.
When the argument to `downcase' is a string, the function creates
and returns a new string in which each letter in the argument that
is upper case is converted to lower case. When the argument to
`downcase' is a character, `downcase' returns the corresponding
lower case character. This value is an integer. If the original
character is lower case, or is not a letter, then the value equals
the original character.
(downcase "The cat in the hat")
=> "the cat in the hat"
(downcase ?X)
=> 120
- Function: upcase STRING-OR-CHAR
This function converts a character or a string to upper case.
When the argument to `upcase' is a string, the function creates
and returns a new string in which each letter in the argument that
is lower case is converted to upper case.
When the argument to `upcase' is a character, `upcase' returns the
corresponding upper case character. This value is an integer. If
the original character is upper case, or is not a letter, then the
value equals the original character.
(upcase "The cat in the hat")
=> "THE CAT IN THE HAT"
(upcase ?x)
=> 88
- Function: capitalize STRING-OR-CHAR
This function capitalizes strings or characters. If
STRING-OR-CHAR is a string, the function creates and returns a new
string, whose contents are a copy of STRING-OR-CHAR in which each
word has been capitalized. This means that the first character of
each word is converted to upper case, and the rest are converted
to lower case.
The definition of a word is any sequence of consecutive characters
that are assigned to the word constituent syntax class in the
current syntax table (*Note Syntax Class Table::).
When the argument to `capitalize' is a character, `capitalize' has
the same result as `upcase'.
(capitalize "The cat in the hat")
=> "The Cat In The Hat"
(capitalize "THE 77TH-HATTED CAT")
=> "The 77th-Hatted Cat"
(capitalize ?x)
=> 88
File: elisp, Node: Case Table, Prev: Character Case, Up: Strings and Characters
The Case Table
==============
You can customize case conversion by installing a special "case
table". A case table specifies the mapping between upper case and lower
case letters. It affects both the string and character case conversion
functions (see the previous section) and those that apply to text in the
buffer (*note Case Changes::.). You need a case table if you are using
a language which has letters other than the standard ASCII letters.
A case table is a list of this form:
(DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
where each element is either `nil' or a string of length 256. The
element DOWNCASE says how to map each character to its lower-case
equivalent. The element UPCASE maps each character to its upper-case
equivalent. If lower and upper case characters are in one-to-one
correspondence, use `nil' for UPCASE; then Emacs deduces the upcase
table from DOWNCASE.
For some languages, upper and lower case letters are not in
one-to-one correspondence. There may be two different lower case
letters with the same upper case equivalent. In these cases, you need
to specify the maps for both directions.
The element CANONICALIZE maps each character to a canonical
equivalent; any two characters that are related by case-conversion have
the same canonical equivalent character.
The element EQUIVALENCES is a map that cyclicly permutes each
equivalence class (of characters with the same canonical equivalent).
(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
likewise for each set of equivalent characters.)
When you construct a case table, you can provide `nil' for
CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
string from CANONICALIZE. In a case table that is actually in use,
those components are non-`nil'. Do not try to specify EQUIVALENCES
without also specifying CANONICALIZE.
Each buffer has a case table. Emacs also has a "standard case
table" which is copied into each buffer when you create the buffer.
Changing the standard case table doesn't affect any existing buffers.
Here are the functions for working with case tables:
- Function: case-table-p OBJECT
This predicate returns non-`nil' if OBJECT is a valid case table.
- Function: set-standard-case-table TABLE
This function makes TABLE the standard case table, so that it will
apply to any buffers created subsequently.
- Function: standard-case-table
This returns the standard case table.
- Function: current-case-table
This function returns the current buffer's case table.
- Function: set-case-table TABLE
This sets the current buffer's case table to TABLE.
The following three functions are convenient subroutines for packages
that define non-ASCII character sets. They modify a string
DOWNCASE-TABLE provided as an argument; this should be a string to be
used as the DOWNCASE part of a case table. They also modify the
standard syntax table. *Note Syntax Tables::.
- Function: set-case-syntax-pair UC LC DOWNCASE-TABLE
This function specifies a pair of corresponding letters, one upper
case and one lower case.
- Function: set-case-syntax-delims L R DOWNCASE-TABLE
This function makes characters L and R a matching pair of
case-invariant delimiters.
- Function: set-case-syntax CHAR SYNTAX DOWNCASE-TABLE
This function makes CHAR case-invariant, with syntax SYNTAX.
- Command: describe-buffer-case-table
This command displays a description of the contents of the current
buffer's case table.
You can load the library `iso-syntax' to set up the standard syntax
table and define a case table for the 8-bit ISO Latin 1 character set.
File: elisp, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
Lists
*****
A "list" represents a sequence of zero or more elements (which may
be any Lisp objects). The important difference between lists and
vectors is that two or more lists can share part of their structure; in
addition, you can insert or delete elements in a list without copying
the whole list.
* Menu:
* Cons Cells:: How lists are made out of cons cells.
* Lists as Boxes:: Graphical notation to explain lists.
* List-related Predicates:: Is this object a list? Comparing two lists.
* List Elements:: Extracting the pieces of a list.
* Building Lists:: Creating list structure.
* Modifying Lists:: Storing new pieces into an existing list.
* Sets And Lists:: A list can represent a finite mathematical set.
* Association Lists:: A list can represent a finite relation or mapping.
File: elisp, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
Lists and Cons Cells
====================
Lists in Lisp are not a primitive data type; they are built up from
"cons cells". A cons cell is a data object that represents an ordered
pair. It records two Lisp objects, one labeled as the CAR, and the
other labeled as the CDR. These names are traditional; see *Note Cons
Cell Type::. CDR is pronounced "could-er."
A list is a series of cons cells chained together, one cons cell per
element of the list. By convention, the CARs of the cons cells are the
elements of the list, and the CDRs are used to chain the list: the CDR
of each cons cell is the following cons cell. The CDR of the last cons
cell is `nil'. This asymmetry between the CAR and the CDR is entirely
a matter of convention; at the level of cons cells, the CAR and CDR
slots have the same characteristics.
Because most cons cells are used as part of lists, the phrase "list
structure" has come to mean any structure made out of cons cells.
The symbol `nil' is considered a list as well as a symbol; it is the
list with no elements. For convenience, the symbol `nil' is considered
to have `nil' as its CDR (and also as its CAR).
The CDR of any nonempty list L is a list containing all the elements
of L except the first.
File: elisp, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
Lists as Linked Pairs of Boxes
==============================
A cons cell can be illustrated as a pair of boxes. The first box
represents the CAR and the second box represents the CDR. Here is an
illustration of the two-element list, `(tulip lily)', made from two
cons cells:
--------------- ---------------
| car | cdr | | car | cdr |
| tulip | o---------->| lily | nil |
| | | | | |
--------------- ---------------
Each pair of boxes represents a cons cell. Each box "refers to",
"points to" or "contains" a Lisp object. (These terms are synonymous.)
The first box, which is the CAR of the first cons cell, contains the
symbol `tulip'. The arrow from the CDR of the first cons cell to the
second cons cell indicates that the CDR of the first cons cell points
to the second cons cell.
The same list can be illustrated in a different sort of box notation
like this:
___ ___ ___ ___
|___|___|--> |___|___|--> nil
| |
| |
--> tulip --> lily
Here is a more complex illustration, showing the three-element list,
`((pine needles) oak maple)', the first element of which is a
two-element list:
___ ___ ___ ___ ___ ___
|___|___|--> |___|___|--> |___|___|--> nil
| | |
| | |
| --> oak --> maple
|
| ___ ___ ___ ___
--> |___|___|--> |___|___|--> nil
| |
| |
--> pine --> needles
The same list represented in the first box notation looks like this:
-------------- -------------- --------------
| car | cdr | | car | cdr | | car | cdr |
| o | o------->| oak | o------->| maple | nil |
| | | | | | | | | |
-- | --------- -------------- --------------
|
|
| -------------- ----------------
| | car | cdr | | car | cdr |
------>| pine | o------->| needles | nil |
| | | | | |
-------------- ----------------
*Note Cons Cell Type::, for the read and print syntax of cons cells
and lists, and for more "box and arrow" illustrations of lists.
File: elisp, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
Predicates on Lists
===================
The following predicates test whether a Lisp object is an atom, is a
cons cell or is a list, or whether it is the distinguished object
`nil'. (Many of these predicates can be defined in terms of the
others, but they are used so often that it is worth having all of them.)
- Function: consp OBJECT
This function returns `t' if OBJECT is a cons cell, `nil'
otherwise. `nil' is not a cons cell, although it *is* a list.
- Function: atom OBJECT
This function returns `t' if OBJECT is an atom, `nil' otherwise.
All objects except cons cells are atoms. The symbol `nil' is an
atom and is also a list; it is the only Lisp object that is both.
(atom OBJECT) == (not (consp OBJECT))
- Function: listp OBJECT
This function returns `t' if OBJECT is a cons cell or `nil'.
Otherwise, it returns `nil'.
(listp '(1))
=> t
(listp '())
=> t
- Function: nlistp OBJECT
This function is the opposite of `listp': it returns `t' if OBJECT
is not a list. Otherwise, it returns `nil'.
(listp OBJECT) == (not (nlistp OBJECT))
- Function: null OBJECT
This function returns `t' if OBJECT is `nil', and returns `nil'
otherwise. This function is identical to `not', but as a matter
of clarity we use `null' when OBJECT is considered a list and
`not' when it is considered a truth value (see `not' in *Note
Combining Conditions::).
(null '(1))
=> nil
(null '())
=> t
File: elisp, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
Accessing Elements of Lists
===========================
- Function: car CONS-CELL
This function returns the value pointed to by the first pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CAR of CONS-CELL.
As a special case, if CONS-CELL is `nil', then `car' is defined to
return `nil'; therefore, any list is a valid argument for `car'.
An error is signaled if the argument is not a cons cell or `nil'.
(car '(a b c))
=> a
(car '())
=> nil
- Function: cdr CONS-CELL
This function returns the value pointed to by the second pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CDR of CONS-CELL.
As a special case, if CONS-CELL is `nil', then `cdr' is defined to
return `nil'; therefore, any list is a valid argument for `cdr'.
An error is signaled if the argument is not a cons cell or `nil'.
(cdr '(a b c))
=> (b c)
(cdr '())
=> nil
- Function: car-safe OBJECT
This function lets you take the CAR of a cons cell while avoiding
errors for other data types. It returns the CAR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
`car', which signals an error if OBJECT is not a list.
(car-safe OBJECT)
==
(let ((x OBJECT))
(if (consp x)
(car x)
nil))
- Function: cdr-safe OBJECT
This function lets you take the CDR of a cons cell while avoiding
errors for other data types. It returns the CDR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
`cdr', which signals an error if OBJECT is not a list.
(cdr-safe OBJECT)
==
(let ((x OBJECT))
(if (consp x)
(cdr x)
nil))
- Function: nth N LIST
This function returns the Nth element of LIST. Elements are
numbered starting with zero, so the CAR of LIST is element number
zero. If the length of LIST is N or less, the value is `nil'.
If N is negative, `nth' returns the first element of LIST.
(nth 2 '(1 2 3 4))
=> 3
(nth 10 '(1 2 3 4))
=> nil
(nth -3 '(1 2 3 4))
=> 1
(nth n x) == (car (nthcdr n x))
- Function: nthcdr N LIST
This function returns the Nth CDR of LIST. In other words, it
removes the first N links of LIST and returns what follows.
If N is zero or negative, `nthcdr' returns all of LIST. If the
length of LIST is N or less, `nthcdr' returns `nil'.
(nthcdr 1 '(1 2 3 4))
=> (2 3 4)
(nthcdr 10 '(1 2 3 4))
=> nil
(nthcdr -3 '(1 2 3 4))
=> (1 2 3 4)
File: elisp, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
Building Cons Cells and Lists
=============================
Many functions build lists, as lists reside at the very heart of
Lisp. `cons' is the fundamental list-building function; however, it is
interesting to note that `list' is used more times in the source code
for Emacs than `cons'.
- Function: cons OBJECT1 OBJECT2
This function is the fundamental function used to build new list
structure. It creates a new cons cell, making OBJECT1 the CAR,
and OBJECT2 the CDR. It then returns the new cons cell. The
arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
often OBJECT2 is a list.
(cons 1 '(2))
=> (1 2)
(cons 1 '())
=> (1)
(cons 1 2)
=> (1 . 2)
`cons' is often used to add a single element to the front of a
list. This is called "consing the element onto the list". For
example:
(setq list (cons newelt list))
Note that there is no conflict between the variable named `list'
used in this example and the function named `list' described below;
any symbol can serve both purposes.
- Function: list &rest OBJECTS
This function creates a list with OBJECTS as its elements. The
resulting list is always `nil'-terminated. If no OBJECTS are
given, the empty list is returned.
(list 1 2 3 4 5)
=> (1 2 3 4 5)
(list 1 2 '(3 4 5) 'foo)
=> (1 2 (3 4 5) foo)
(list)
=> nil
- Function: make-list LENGTH OBJECT
This function creates a list of length LENGTH, in which all the
elements have the identical value OBJECT. Compare `make-list'
with `make-string' (*note Creating Strings::.).
(make-list 3 'pigs)
=> (pigs pigs pigs)
(make-list 0 'pigs)
=> nil
- Function: append &rest SEQUENCES
This function returns a list containing all the elements of
SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
the last one should be a list. All arguments except the last one
are copied, so none of them are altered.
More generally, the final argument to `append' may be any Lisp
object. The final argument is not copied or converted; it becomes
the CDR of the last cons cell in the new list. If the final
argument is itself a list, then its elements become in effect
elements of the result list. If the final element is not a list,
the result is a "dotted list" since its final CDR is not `nil' as
required in a true list.
See `nconc' in *Note Rearrangement::, for a way to join lists with
no copying.
Here is an example of using `append':
(setq trees '(pine oak))
=> (pine oak)
(setq more-trees (append '(maple birch) trees))
=> (maple birch pine oak)
trees
=> (pine oak)
more-trees
=> (maple birch pine oak)
(eq trees (cdr (cdr more-trees)))
=> t
You can see how `append' works by looking at a box diagram. The
variable `trees' is set to the list `(pine oak)' and then the
variable `more-trees' is set to the list `(maple birch pine oak)'.
However, the variable `trees' continues to refer to the original
list:
more-trees trees
| |
| ___ ___ ___ ___ -> ___ ___ ___ ___
--> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
| | | |
| | | |
--> maple -->birch --> pine --> oak
An empty sequence contributes nothing to the value returned by
`append'. As a consequence of this, a final `nil' argument forces
a copy of the previous argument.
trees
=> (pine oak)
(setq wood (append trees ()))
=> (pine oak)
wood
=> (pine oak)
(eq wood trees)
=> nil
This once was the usual way to copy a list, before the function
`copy-sequence' was invented. *Note Sequences Arrays Vectors::.
With the help of `apply', we can append all the lists in a list of
lists:
(apply 'append '((a b c) nil (x y z) nil))
=> (a b c x y z)
If no SEQUENCES are given, `nil' is returned:
(append)
=> nil
Here are some examples where the final argument is not a list:
(append '(x y) 'z)
=> (x y . z)
(append '(x y) [z])
=> (x y . [z])
The second example shows that when the final argument is a
sequence but not a list, the sequence's elements do not become
elements of the resulting list. Instead, the sequence becomes the
final CDR, like any other non-list final argument.
The `append' function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead
of the original integers. *Don't use this feature; we plan to
eliminate it. If you already use this feature, change your
programs now!* The proper way to convert an integer to a decimal
number in this way is with `format' (*note Formatting Strings::.)
or `number-to-string' (*note String Conversion::.).
- Function: reverse LIST
This function creates a new list whose elements are the elements of
LIST, but in reverse order. The original argument LIST is *not*
altered.
(setq x '(1 2 3 4))
=> (1 2 3 4)
(reverse x)
=> (4 3 2 1)
x
=> (1 2 3 4)
File: elisp, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
Modifying Existing List Structure
=================================
You can modify the CAR and CDR contents of a cons cell with the
primitives `setcar' and `setcdr'.
Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
to alter list structure; they change structure the same way as
`setcar' and `setcdr', but the Common Lisp functions return the
cons cell while `setcar' and `setcdr' return the new CAR or CDR.
* Menu:
* Setcar:: Replacing an element in a list.
* Setcdr:: Replacing part of the list backbone.
This can be used to remove or add elements.
* Rearrangement:: Reordering the elements in a list; combining lists.
File: elisp, Node: Setcar, Next: Setcdr, Up: Modifying Lists
Altering List Elements with `setcar'
------------------------------------
Changing the CAR of a cons cell is done with `setcar'. When used on
a list, `setcar' replaces one element of a list with a different
element.
- Function: setcar CONS OBJECT
This function stores OBJECT as the new CAR of CONS, replacing its
previous CAR. It returns the value OBJECT. For example:
(setq x '(1 2))
=> (1 2)
(setcar x 4)
=> 4
x
=> (4 2)
When a cons cell is part of the shared structure of several lists,
storing a new CAR into the cons changes one element of each of these
lists. Here is an example:
;; Create two lists that are partly shared.
(setq x1 '(a b c))
=> (a b c)
(setq x2 (cons 'z (cdr x1)))
=> (z b c)
;; Replace the CAR of a shared link.
(setcar (cdr x1) 'foo)
=> foo
x1 ; Both lists are changed.
=> (a foo c)
x2
=> (z foo c)
;; Replace the CAR of a link that is not shared.
(setcar x1 'baz)
=> baz
x1 ; Only one list is changed.
=> (baz foo c)
x2
=> (z foo c)
Here is a graphical depiction of the shared structure of the two
lists in the variables `x1' and `x2', showing why replacing `b' changes
them both:
___ ___ ___ ___ ___ ___
x1---> |___|___|----> |___|___|--> |___|___|--> nil
| --> | |
| | | |
--> a | --> b --> c
|
___ ___ |
x2--> |___|___|--
|
|
--> z
Here is an alternative form of box diagram, showing the same
relationship:
x1:
-------------- -------------- --------------
| car | cdr | | car | cdr | | car | cdr |
| a | o------->| b | o------->| c | nil |
| | | -->| | | | | |
-------------- | -------------- --------------
|
x2: |
-------------- |
| car | cdr | |
| z | o----
| | |
--------------
File: elisp, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
Altering the CDR of a List
--------------------------
The lowest-level primitive for modifying a CDR is `setcdr':
- Function: setcdr CONS OBJECT
This function stores OBJECT as the new CDR of CONS, replacing its
previous CDR. It returns the value OBJECT.
Here is an example of replacing the CDR of a list with a different
list. All but the first element of the list are removed in favor of a
different sequence of elements. The first element is unchanged,
because it resides in the CAR of the list, and is not reached via the
(setq x '(1 2 3))
=> (1 2 3)
(setcdr x '(4))
=> (4)
x
=> (1 4)
You can delete elements from the middle of a list by altering the
CDRs of the cons cells in the list. For example, here we delete the
second element, `b', from the list `(a b c)', by changing the CDR of
the first cell:
(setq x1 '(a b c))
=> (a b c)
(setcdr x1 (cdr (cdr x1)))
=> (c)
x1
=> (a c)
Here is the result in box notation:
--------------------
| |
-------------- | -------------- | --------------
| car | cdr | | | car | cdr | -->| car | cdr |
| a | o----- | b | o-------->| c | nil |
| | | | | | | | |
-------------- -------------- --------------
The second cons cell, which previously held the element `b', still
exists and its CAR is still `b', but it no longer forms part of this
list.
It is equally easy to insert a new element by changing CDRs:
(setq x1 '(a b c))
=> (a b c)
(setcdr x1 (cons 'd (cdr x1)))
=> (d b c)
x1
=> (a d b c)
Here is this result in box notation:
-------------- ------------- -------------
| car | cdr | | car | cdr | | car | cdr |
| a | o | -->| b | o------->| c | nil |
| | | | | | | | | | |
--------- | -- | ------------- -------------
| |
----- --------
| |
| --------------- |
| | car | cdr | |
-->| d | o------
| | |
---------------
File: elisp, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
Functions that Rearrange Lists
------------------------------
Here are some functions that rearrange lists "destructively" by
modifying the CDRs of their component cons cells. We call these
functions "destructive" because they chew up the original lists passed
to them as arguments, to produce a new list that is the returned value.
See `delq', in *Note Sets And Lists::, for another function that
modifies cons cells.
- Function: nconc &rest LISTS
This function returns a list containing all the elements of LISTS.
Unlike `append' (*note Building Lists::.), the LISTS are *not*
copied. Instead, the last CDR of each of the LISTS is changed to
refer to the following list. The last of the LISTS is not
altered. For example:
(setq x '(1 2 3))
=> (1 2 3)
(nconc x '(4 5))
=> (1 2 3 4 5)
x
=> (1 2 3 4 5)
Since the last argument of `nconc' is not itself modified, it is
reasonable to use a constant list, such as `'(4 5)', as in the
above example. For the same reason, the last argument need not be
a list:
(setq x '(1 2 3))
=> (1 2 3)
(nconc x 'z)
=> (1 2 3 . z)
x
=> (1 2 3 . z)
A common pitfall is to use a quoted constant list as a non-last
argument to `nconc'. If you do this, your program will change
each time you run it! Here is what happens:
(defun add-foo (x) ; We want this function to add
(nconc '(foo) x)) ; `foo' to the front of its arg.
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo)) x))
(setq xx (add-foo '(1 2))) ; It seems to work.
=> (foo 1 2)
(setq xy (add-foo '(3 4))) ; What happened?
=> (foo 1 2 3 4)
(eq xx xy)
=> t
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
- Function: nreverse LIST
This function reverses the order of the elements of LIST. Unlike
`reverse', `nreverse' alters its argument by reversing the CDRs in
the cons cells forming the list. The cons cell that used to be
the last one in LIST becomes the first cell of the value.
For example:
(setq x '(1 2 3 4))
=> (1 2 3 4)
x
=> (1 2 3 4)
(nreverse x)
=> (4 3 2 1)
;; The cell that was first is now last.
x
=> (1)
To avoid confusion, we usually store the result of `nreverse' back
in the same variable which held the original list:
(setq x (nreverse x))
Here is the `nreverse' of our favorite example, `(a b c)',
presented graphically:
Original list head: Reversed list:
------------- ------------- ------------
| car | cdr | | car | cdr | | car | cdr |
| a | nil |<-- | b | o |<-- | c | o |
| | | | | | | | | | | | |
------------- | --------- | - | -------- | -
| | | |
------------- ------------
- Function: sort LIST PREDICATE
This function sorts LIST stably, though destructively, and returns
the sorted list. It compares elements using PREDICATE. A stable
sort is one in which elements with equal sort keys maintain their
relative order before and after the sort. Stability is important
when successive sorts are used to order elements according to
different criteria.
The argument PREDICATE must be a function that accepts two
arguments. It is called with two elements of LIST. To get an
increasing order sort, the PREDICATE should return `t' if the
first element is "less than" the second, or `nil' if not.
The destructive aspect of `sort' is that it rearranges the cons
cells forming LIST by changing CDRs. A nondestructive sort
function would create new cons cells to store the elements in their
sorted order. If you wish to make a sorted copy without
destroying the original, copy it first with `copy-sequence' and
then sort.
Sorting does not change the CARs of the cons cells in LIST; the
cons cell that originally contained the element `a' in LIST still
has `a' in its CAR after sorting, but it now appears in a
different position in the list due to the change of CDRs. For
example:
(setq nums '(1 3 2 6 5 4 0))
=> (1 3 2 6 5 4 0)
(sort nums '<)
=> (0 1 2 3 4 5 6)
nums
=> (1 2 3 4 5 6)
Note that the list in `nums' no longer contains 0; this is the same
cons cell that it was before, but it is no longer the first one in
the list. Don't assume a variable that formerly held the argument
now holds the entire sorted list! Instead, save the result of
`sort' and use that. Most often we store the result back into the
variable that held the original list:
(setq nums (sort nums '<))
*Note Sorting::, for more functions that perform sorting. See
`documentation' in *Note Accessing Documentation::, for a useful
example of `sort'.
File: elisp, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
Using Lists as Sets
===================
A list can represent an unordered mathematical set--simply consider a
value an element of a set if it appears in the list, and ignore the
order of the list. To form the union of two sets, use `append' (as
long as you don't mind having duplicate elements). Other useful
functions for sets include `memq' and `delq', and their `equal'
versions, `member' and `delete'.
Common Lisp note: Common Lisp has functions `union' (which avoids
duplicate elements) and `intersection' for set operations, but GNU
Emacs Lisp does not have them. You can write them in Lisp if you
wish.
- Function: memq OBJECT LIST
This function tests to see whether OBJECT is a member of LIST. If
it is, `memq' returns a list starting with the first occurrence of
OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
says that it uses `eq' to compare OBJECT against the elements of
the list. For example:
(memq 'b '(a b c b a))
=> (b c b a)
(memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
=> nil
- Function: delq OBJECT LIST
This function destructively removes all elements `eq' to OBJECT
from LIST. The letter `q' in `delq' says that it uses `eq' to
compare OBJECT against the elements of the list, like `memq'.
When `delq' deletes elements from the front of the list, it does so
simply by advancing down the list and returning a sublist that starts
after those elements:
(delq 'a '(a b c)) == (cdr '(a b c))
When an element to be deleted appears in the middle of the list,
removing it involves changing the CDRs (*note Setcdr::.).
(setq sample-list '(a b c (4)))
=> (a b c (4))
(delq 'a sample-list)
=> (b c (4))
sample-list
=> (a b c (4))
(delq 'c sample-list)
=> (a b (4))
sample-list
=> (a b (4))
Note that `(delq 'c sample-list)' modifies `sample-list' to splice
out the third element, but `(delq 'a sample-list)' does not splice
anything--it just returns a shorter list. Don't assume that a variable
which formerly held the argument LIST now has fewer elements, or that
it still holds the original list! Instead, save the result of `delq'
and use that. Most often we store the result back into the variable
that held the original list:
(setq flowers (delq 'rose flowers))
In the following example, the `(4)' that `delq' attempts to match
and the `(4)' in the `sample-list' are not `eq':
(delq '(4) sample-list)
=> (a c (4))
The following two functions are like `memq' and `delq' but use
`equal' rather than `eq' to compare elements. They are new in Emacs 19.
- Function: member OBJECT LIST
The function `member' tests to see whether OBJECT is a member of
LIST, comparing members with OBJECT using `equal'. If OBJECT is a
member, `member' returns a list starting with its first occurrence
in LIST. Otherwise, it returns `nil'.
Compare this with `memq':
(member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
=> ((2))
(memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
=> nil
;; Two strings with the same contents are `equal'.
(member "foo" '("foo" "bar"))
=> ("foo" "bar")
- Function: delete OBJECT LIST
This function destructively removes all elements `equal' to OBJECT
from LIST. It is to `delq' as `member' is to `memq': it uses
`equal' to compare elements with OBJECT, like `member'; when it
finds an element that matches, it removes the element just as
`delq' would. For example:
(delete '(2) '((2) (1) (2)))
=> ((1))
Common Lisp note: The functions `member' and `delete' in GNU Emacs
Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
versions do not use `equal' to compare elements.
See also the function `add-to-list', in *Note Setting Variables::,
for another way to add an element to a list stored in a variable.